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Typical REST Versioning 


Some time T1 


Some time T2 

GET /server/1 


GET /server/1 

{ 


{ 

"server": { 


"server": { 

"id": 1, 


"id": 1, 

"name": "myserver", 


"name": "myserver", 

"ips": ["10.42.100.1"] 


"description": 

} 


"ips": ["10.42.100.1"] 

} 


} 



} 


A 




Generally accepted rules: 

• clients should not break on additional keys 

• adding new attributes is backwards compatible 

• there is only ever going to be one version publicly accessable* 

• the API will never roll back once in production (i.e. description can't just disappear once it's out there) 
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Typical REST Versioning 


Some time T1 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"ips": ["10.42.100.1"] 

} 

} 


Some time T2 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"ips": ["10.42.100.1"] 

} 
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All works very well for single vendor services 

• Github 

• AWS 

• Meetup 

• etc 
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Some time T3 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description":"....", 
"tags": ["db", "ha"], 
"ips": ["10.42.100.1"] 

} 

} 







Typical REST Versioning 



Some time T2 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"ips": ["10.42.100.1"] 

} 

} 



Development Workflow 
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Some time T3 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"tags": ["db", "ha"], 
"ips": ["10.42.100.1"] 

} 

} 


push to prod 






Upstream Versioning 



Upstream Development Workflow 
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Upstream Code going into Clouds and Products 
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Upstream Releases 





Client Perspective 


Liberty Mitaka Newton 


Cloud Product A LJ. 


Mitaka 
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Upstream Releases 














Client Experiencing A —*■ B —*■ C 


Cloud A 

GET /server/1 


Cloud B 

GET /server/1 


Cloud C 

GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"ips": ["10.42.100.1"] 

} 

} 


{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"tags": ["db", "ha"], 
"ips": ["10.42.100.1"] 

} 

} 


{ 

"server": { 

"id": 1, 

"name": "myserver", 
"ips": ["10.42.100.1"] 

} 

} 


A 


to 


Time's Arrow seems to go backwards. 

Software is made to work on Cloud A, points at Cloud B still works, Cloud C is missing parameters 
leading to possibly confusing late failures. 
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The Assumed Good Enough Rules 

don't account for a 

Different Team Developing the Software 
than Deploying it 
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REST API Microversions 




Client Experiencing A —*■ B —*■ C 


2.25 2.40 Base 


Cloud A 

GET /server/1 


Cloud B 

GET /server/1 


Cloud C 

GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"ips": ["10.42.100.1"] 

} 

} 


{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"tags": ["db", "ha"], 
"ips": ["10.42.100.1"] 

} 

} 


{ 

"server": { 

"id": 1, 

"name": "myserver", 
"ips": ["10.42.100.1"] 

} 

} 


A 


to 


Time's Arrow seems to go backwards. 

Software is made to work on Cloud A, points at Cloud B still works, Cloud C is missing parameters 
leading to possibly confusing late failures. 
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Client Experiencing A —*■ B —> C 

At time T3 with Microversions 


Cloud A 

Cloud B 

Cloud C 


GET /server/1 


GET /server/1 


GET /server/1 


{ 


{ 


{ 


"server": { 


"server": { 


"server": { 

Base 

"id": 1, 


"id": 1, 


"id": 1, 


"name": "myserver", 


"name": "myserver", 


"name": "myserver", 


"ips": ["10.42.100.1"] 


"ips": ["10.42.100.1"] 


"ips": ["10.42.100.1"] 


} 


} 


} 


} 


} 


} 





Cloud A 


Cloud B 


Cloud C 



GET /server/1 

GET /server/1 

GET /server/1 


OpenStack-Version: compute 2.25 


OpenStack-Version: compute 2.25 


OpenStack-Version: compute 2.25 


{ 


{ 


Status: 400 

2.25 

"server": { 


"server": { 


Version not found 


"id": 1, 


"id": 1, 




"name": "myserver", 


"name": "myserver", 




"description": "great server", 


"description": "great server", 




"ips": ["10.42.100.1"] 


"ips": ["10.42.100.1"] 



i 

} 


} 


V 

} 


} 
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REST API Microversions 


• Concept 

Inspired by HTTP Content negotiation 

Allow incremental feature roll out in API instead of waiting for major version bump 
Introduced in 2014 in OpenStack Nova / Ironic (expanded to 6 projects now) 

• Technical Details 

Discoverable in root version document 
An explicit version header on each request 
Global incrementing version for entire service 
Defaults to minimum value 
Services continue to support old versions 
Hard 400 fail if version not found 



Very long history of 
getting here available 
at bar later upon 
request 


• Blog writeup including personas - https://dague.net/api-mv 
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Questions for the Future 


• Raising minimum versions? 

• How much compat code do we need to 
keep? 

• Machine specifications? 
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OpenStack Nova Compute: 

GET/ 

{ 

"versions": [ 

{ 

"id": "v2.0", 

"links": [ 

{ 

"href": "http://openstack.example.com/v2/", 
"rel": "self" 

} 

]. 

"status": "SUPPORTED", 

"version":"", 

"min_version": 

}, 

{ 

"id": "v2.1", 

"links": [ 

{ 

"href": "http://openstack.example.eom/v2.l/", 
"rel": "self" 

} 

]. 

"status": "CURRENT", 

"version": "2.53", 

"min_version": "2.1", 

} 

] 

} 




OpenStack and OpenAPI 


OpenStack APIs vs OpenAPI 


• Many OpenStack APIs evolved around WADL 

• Attempt to retrofit OpenAPI definitions in 2015 to many core APIs, 2 key issues 

- Duplicate actions that don't map to Swagger/OpenAPI 

• POST /servers/{id}/action 
{"reboot": 

• POST /servers/{id}/action 
{"resize": {"flavor": "ml.large"}} 

- Micro versions also don't really fit 

• Could they? 
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Parting Thoughts 


THANKS! 


• There are specific challenges to Open Source network consumable services being 
deployed in multiple organizationally controlled clouds 

- Tooling today largely doesn't consider that 

• If we don't consider it, we make it harder to do non single vendor Open Source all the 
way to the edge 

- How do we prevent that? 


https://dague.net/api-mv 

Sean Dague 
dague.net 

sean.dague@ibm.com / sean@dague.net 
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